{ "cells": [ { "cell_type": "markdown", "source": [ "# Solving Sudokus with a Genetic Algorithm\n", "\n", "## Try me\n", " [![Open In Colab](../../_static/colabs_badge.png)](https://colab.research.google.com/github/ffraile/operations-research-notebooks/blob/main/docs/source/MIP/tutorials/sudoku%20GA.ipynb)[![Binder](../../_static/binder_badge.png)](https://mybinder.org/v2/gh/ffraile/operations-research-notebooks/main?labpath=docs%2Fsource%2FMIP%2Ftutorials%2Fsudoku%20GA.ipynb)\n", "\n", "## Introduction\n", "Sudoku is a very popular japanese game invented in the 70s. Basically, the objective is to fill in a grid of 9x9 cells\n", "with digits, so that in each column, in each row and in each 3x3 grid there is exactly one digit from 1-9. The following\n", "image shows an example of a Sudoku puzzle.\n", "\n", "![Sudoku](img/Sudoku-by-L2G-20050714.png){width=50%}\n", "\n", "
Tim Stellmach - public domain, wikipedia

\n", "\n", "We can model this problem as a combinatorial optimization problem and apply different combinatorial algorithms and heuristics to solve it. Although it clearly might not be the best alternative, we are going to use this very well known problem\n", "to describe how genetic algorithms work and what are the main trade-offs that arise when solving optimization problems\n", "with genetic algorithms. \n", "\n", "## Requirements\n", "You need to install Numpy in your Python Kernel runtime. Install Numpy if you are running on Binder or you do not have Numpy install in your system:" ], "metadata": { "collapsed": false } }, { "cell_type": "code", "execution_count": null, "outputs": [], "source": [ "!pip install numpy" ], "metadata": { "collapsed": false } }, { "cell_type": "markdown", "source": [ "## Evolutionary Algorithms in a nutshell\n", "Evolutionary algorithms are a family of algorithms that are inspired by the process of natural selection. The main idea is to represent the solution of the problem as a mathematical object called a **genome**, and to combine different genomes to generate new ones. The genomes that are more fit to the problem are more likely to be selected to generate new genomes, and the process is repeated until a solution is found, or a maximum number of iterations is reached. These are the main steps of an evolutionary algorithm:\n", "\n", "- **Initialization**: Generate an initial set of genomes. We will call this set the **population**.\n", "- **Evaluation**: Evaluate the fitness of each genome in the population.\n", "- **Selection**: Select the genomes that are more fit to the problem.\n", "- **Crossover**: Combine the selected genomes to generate new genomes.\n", "- **Mutation**: Mutate the new genomes.\n", "- **Termination**: Check if the termination criteria is met. If not, go to step 2.\n", "\n", "Evolutionary algorithms are very flexible, and well-fitted to solve many combinatorial optimization problems. They are also very easy to implement, and they do not require a deep knowledge of the problem to be solved to achieve good results. However, they are not very efficient, and they are not guaranteed to find the optimal solution.\n", "\n", "You can find a slightly more extended explanation of Genetic algorithms in this [tutorial](genetic%20algorithms.ipynb)\n", "\n", "## Approach 1: Naive approach\n", "One of the main advantages of genetic algorithms is that we do not need to have a priori an in-depth knowledge of the \n", "problem, we can use simple rules or heuristics to generate the genome of each iteration, and let the fitness function \n", "select the fittest alternative. \n", "The simplest way to model the Sudoku as a combinatorial optimization problem would be to regard the solution as a \n", "permutation of the missing digits. For instance, if we look at the solution of the example above: \n", "\n", "![Sudoku Solved](img/Sudoku_Puzzle_by_L2G-20050714_solution_standardized_layout.png){width=50%}\n", "\n", "
Tim Stellmach - public domain, wikipedia

\n", "\n", "We can actually assign to every unknown cell an index from 1 to the number of unknowns, from left to right and top to bottom, such that the solution is the ordered set:\n", "\n", "$s = (s_1, s_2, ..., s_N) = (4, 6, 8, 9, 1, 2, 7, 2, 3, 4, 8, 1, 3, 4, 2, 4, 7, 5, 9, 7, 1, 4, 2, 2, 6, 5, 7, 9, 1, 3, 9, 4, 8, 5, 9, 1, 5, 3,\\\\\n", "7, 4, 2, 8, 7, 6, 3, 3, 4, 5, 2, 6, 1)$\n", "\n", "At the beginning of the problem, we do not know the exact value that we need to assign to each cell, that is, we do not know that $s_1 = 4$ or that $s_5 = 5$, but we know that it will be a value that is missing, and \n", "it is very easy to calculate the values that are missing, just by counting the digits that are present, because we know that each digit appears nine time in the solution. So, with this simple procedure, we can determine at the beginning of the problem which are the digits that are missing: \n", "\n", "$$c = \\{1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 4, 4, 4,\n", " 4, 4, 4, 4, 4, 5, 5, 5, 5, 5, 6, 6, 6, 6, 7, 7, 7, 7, 7, 7, 8, 8,\n", " 8, 8, 9, \\\\\n", " 9, 9, 9, 9\\}$$\n", "\n", "And we know that the solution $s$ is going to be a [permutation](https://en.wikipedia.org/wiki/Permutation) of these elements!\n", "\n", "### Assessment of the search space\n", "We need to find the right permutation though, and there are $N!$ number of permutations, where $N$ is as noted above the \n", "total number of missing digits in our problem. In this case $N=51$ so there are: \n", "\n", "$$N! = 51! = 1551118753287382280224243016469303211063259720016986112000000000000$$\n", "\n", "possible combinations, which are many! Luckily for us, there are [repetitions](https://en.wikipedia.org/wiki/Permutation#Permutations_with_repetition), since some digits are repeated.\n", "Considering that there are 6 1's, 7 2's, 6 3's, 8 4's, 5 5's, 4 6's, 6 7's, 4 8's and 5 9's, we can calculate the number of permutations with repetitions as:\n", "\n", "\n", "$$\\frac{51!}{6!·7!·6!·8!·5!·4!·6!·4!·5!}=2465536997482928914408092530982635167547392 = 2.47*10^{42}$$\n", "\n", "Which is still a really large number of possible combinations! The question is, are they too many for a genetic algorithm\n", "to find a solution?\n", "We will find out soon enough, but first, let's discuss how our genetic algorithm is going to work. Step by step:\n", "\n", "### Initialisation\n", "The first step is to generate an initial **genome** (all genes of a set of possible solutions). A gene is going to \n", "represent the value of a digit in a position of the Sudoku, and all the genes or chromosome of a solution, all the values\n", "of all digits missing in the problem. \n", "Basically, to generate the genome of the first population, we can generate just as many permutations of c as\n", "the size of the initial population. Say the initial population size is $P$, so initialising the genome is basically to \n", "obtain $P$ permutations of $c$. Let us define a function $\\tau(c)$ that randomly re-arranges the items of an array $c$ \n", "and therefore returns a random permutation out of all possible permutations. so, our initial genome $G_0$ is going to \n", "be just a set of permutations of c: \n", "\n", "$$G_0 = [g_{01}, g_{02}, ...g_{0P}]$$\n", "\n", "$$g_{0k} = \\tau(c) \\quad \\forall k \\in [1, P]$$\n", "\n", "As a reference, the numpy function [shuffle](https://numpy.org/doc/stable/reference/random/generated/numpy.random.shuffle.html) provides such a re-arrangement.\n", "\n", "\n", "### Fitness function\n", "Now, the second step is to evaluate the fitness function. We can define a fitness function that counts the number of \n", "duplicated digits in every row, in every column, and in every 3x3 block. That is, if a digit appears two times in a row, \n", "the fitness function will add 1, and if a digit appears twice in a column, it will add 1, same if it appears twice in a \n", "block. So let us define this fitness function as $f(g_{ik})$ and obviously the result is going to be an integer number.\n", "Furthermore, the $fitness array$: \n", "\n", "$$f_0 = [f(g_{01}), f(g_{02}), ..., f(g_{0P})]$$\n", "\n", "will contain the fitness of the different candidate solutions in the initial population, and by extension: \n", "\n", "$$f_i = [f(g_{i1}), f(g_{i2}), ..., f(g_{iP})]$$\n", "\n", "will contain the fitness of the different candidate solutions in the population at generation $i$. \n", "\n", "### Selection function\n", "To select the fittest, we just need to select the candidates that contain fewer mistakes, those where the fitness solution\n", "is lower. We just need to sort the elements of the fitness array in ascending order and select some of them for the next\n", "generation. Let us note the selection function as $\\sigma(f_i)$ and as $S$ the number of individuals\n", "that will produce offspring in the next generation. The set of survivals in a generation $i$ is: \n", "\n", "$$s_i = \\sigma(f_i) = [s_{i1}, s_{i2}, ..., s_{iS}]$$\n", "\n", "whereas described, the elements of s will be the $S$ elements of $G_i$ with the lowest fitness function value.\n", "\n", "### Crossover and mutation\n", "We could randomly select two parents from the survivals and combine values in the solution, but we need to ensure that \n", "the result is still a permutation of $c$, so for the sake of simplicity, let us not implement any crossover function and \n", "focus on the generation of mutations of surviving individuals. To generate a mutation, what we can do is copy some values randomly from the parent in the exact same position as they are in the parent, and shuffle the remaining values.\n", "For instance, imagine that our problem was very easy and only missing 3 values. We could select randomly 1 out of the 3 \n", "values and copy it in the exact same location and generate a permutation of the other two elements. If the parent had \n", "all the digits of a valid solution, so will the children, and if we are lucky, the permutation will yield a valid \n", "solution. \n", "Let us note as $R$ the number of digits (or genes) of the parent that we copy, and $N-R$ the number of genes that mutate. \n", "Note that, if we select randomly the $(R)$ genes out of the $N$ genes, this is a combination, and therefore, the number\n", "of possible combinations of $R$ genes out of the parent is:\n", " \n", "$$C^N_R = \\frac{N!}{R!(N-R)!}$$\n", "\n", "And now, we are going to shuffle the $(N-R)$ remaining genes, so there are $(N-R)$ different permutations of these \n", "genes, that combined with the previous result, yield the following total possible different offspring from a single \n", "parent:\n", "\n", "$$\\frac{N!}{R!}$$\n", "\n", "\n", "For instance, the example above, with $N=51$ gaps or blank positions, if we set $R=49$, there are: \n", "\n", "$$C^{51}_{49} = \\frac{N!}{R!(N-R)!} = \\frac{51!}{49!(51-49)!} = \\frac{51*50*49!}{49!*2!} = \\frac{51*50}{2!} = 1275$$\n", "\n", "possible ways to combine the genes, and if we multiply by $2!$, we get 2500 different combinations of a parent. \n", "Now, this is only for 1 parent, if the selection function lets $S$ survivals, we need to multiply by this factor as well\n", "to get the total size of the possible offspring, so for instance, if we set it to 10, the possible different members\n", "in a generation is 25000. \n", " \n", "We really need to fine tune these parameters to make sure that the algorithm is fast, because we need to make sure that \n", "we explore a sufficient proportion of all the possible offspring in the iterations. For instance if $R$ is too small, \n", "the number of possible children will be too large compared to the population size, and it will be very difficult for the\n", "algorithm to find the right solution. Additionally, $(N-R)$ must be at least 2, so that we can at least switch two digits \n", "to generate another solution. On the other hand, if the population size is too large compared to the possible offspring\n", "our algorithm is inefficient because the population size is too large compared to the possible different offspring, and \n", "we will be evaluating several times the same combination of genes in every generation. As a rule of thumb, You need to \n", "make sure that the total number of different offspring in a generation is larger than the population size but in the \n", "same order of magnitude.\n", "\n", "### Termination\n", "Finally, we will terminate when we reach a maximum number of iterations, or when we have found the optimal solution. \n", "We also need to ensure that we can get rid of *bad batches*, meaning that something can go wrong in the mutations and \n", "our algorithm can converge to a solution that can not be fixed with a permutation of N-R numbers of all candidate \n", "solution, that is the fitness function can have *local minimum* and our solution can converge to a local minimum, which \n", "is not optimal, so if we detect for instance that the fitness function does not change in a number of iterations, \n", "we just go back to step 1 and initialise the entire population again. We also need to set another parameter to control \n", "the reset, which will represent the maximum number of iterations without improvement in the fitness function.\n", "\n", "\n", "### Implementation\n", "Ok, the following Python script implements this approach. To try it, you just need to provide the values of your Sudoku \n", "as a Python Array where the digits in [1-9] define the clues or filled digits in your Sudoku, and the 0s represent the \n", "gaps.\n", "\n", "#### Hyper-parameters\n", "The parameters that control the behaviour of the algorithm, or hyperparameters are as described above:\n", "- Number of genes that are passed to children in each generation (R). Default: N-R = 2 \n", "- Population size, the population size of each generation (P), default: 500\n", "- Number of iterations, default: 1000:\n", "- Number of survivals in each generation, default 10\n", "- Number of iterations without improvement, default 10\n", " " ], "metadata": { "collapsed": false } }, { "cell_type": "code", "execution_count": 3, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "all righty, i finished the Sudoku in 84.685776 seconds and 567 iterations: \n", "Best solution is:\n", "[[8. 3. 6. 2. 7. 9. 4. 1. 5.]\n", " [9. 5. 1. 3. 4. 8. 7. 6. 2.]\n", " [4. 7. 2. 1. 5. 6. 3. 8. 9.]\n", " [7. 9. 3. 4. 8. 5. 6. 2. 1.]\n", " [1. 6. 5. 7. 9. 2. 8. 3. 4.]\n", " [2. 8. 4. 6. 1. 3. 9. 5. 7.]\n", " [5. 1. 8. 9. 3. 4. 2. 7. 6.]\n", " [3. 2. 9. 5. 6. 7. 1. 4. 8.]\n", " [6. 4. 7. 8. 2. 1. 5. 9. 3.]]\n" ] }, { "data": { "text/plain": "Text(0, 0.5, 'Error')" }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" }, { "data": { "text/plain": "
", "image/png": "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nTn32bx5M0477TRMmjQJM2fOxBe/+EWMjIyU86nUFNdccw0sy8Lll1/ufI/rLMObb76JT3ziE5g2bRoaGhpw6KGH4vHHH3d+bts2vv71r2PWrFloaGjAkiVL8OKLL+aMsWvXLpx77rlobm5GS0sLLrroIvT19ZX7qVQto6Oj+NrXvob58+ejoaEB++67L771rW/l9OLhOofj4Ycfxumnn47Zs2fDsizcddddOT+XWte///3veNe73oX6+nq0t7fje9/7nv7kbRKYO+64w47H4/ZPfvIT+9lnn7U//elP2y0tLXZnZ2elp1YznHLKKfatt95qb9iwwX7qqafsD37wg/bcuXPtvr4+5z4XX3yx3d7ebq9atcp+/PHH7WOPPdY+7rjjnJ+PjIzYCxcutJcsWWI/+eST9h/+8Ad7+vTp9pVXXlmJp1T1PPbYY/a8efPsww47zL7sssuc73Od9dm1a5e999572xdccIH96KOP2q+88op933332S+99JJzn2uuucZOJpP2XXfdZT/99NP2hz/8YXv+/Pn2nj17nPt84AMfsA8//HB77dq19l/+8hd7v/32s88555xKPKWq5Oqrr7anTZtm33PPPfarr75q33nnnXZjY6P9wx/+0LkP1zkcf/jDH+yvfvWr9m9+8xsbgP3b3/425+cS69rd3W23trba5557rr1hwwb7l7/8pd3Q0GD/53/+p9bcKWRCcPTRR9vLli1zvh4dHbVnz55tr1ixooKzqm22b99uA7BXr15t27Ztd3V12XV1dfadd97p3Oe5556zAdhr1qyxbTv9hxeJROyOjg7nPjfddJPd3NxsDw4OlvcJVDm9vb32/vvvb99///32u9/9bkfIcJ1l+PKXv2yfcMIJBX+eSqXstrY2+/vf/77zva6uLjuRSNi//OUvbdu27Y0bN9oA7HXr1jn3+eMf/2hblmW/+eab5iZfQ5x22mn2pz71qZzvnXXWWfa5555r2zbXWYp8ISO1rjfeeKM9ZcqUnM+NL3/5y/aBBx6oNV8eLQVkaGgI69evx5IlS5zvRSIRLFmyBGvWrKngzGqb7u5uAMDUqVMBAOvXr8fw8HDOOi9YsABz58511nnNmjU49NBD0dra6tznlFNOQU9PD5599tkyzr76WbZsGU477bSc9QS4zlL8/ve/x1FHHYWPfvSjmDlzJo444gj8+Mc/dn7+6quvoqOjI2edk8kkjjnmmJx1bmlpwVFHHeXcZ8mSJYhEInj00UfL92SqmOOOOw6rVq3CCy+8AAB4+umn8cgjj+DUU08FwHU2hdS6rlmzBieeeCLi8bhzn1NOOQWbNm3C22+/HXp+475ppDQ7duzA6Ohozoc6ALS2tuL555+v0Kxqm1QqhcsvvxzHH388Fi5cCADo6OhAPB5HS0tLzn1bW1vR0dHh3MfrdVA/I2nuuOMOPPHEE1i3bt2Yn3GdZXjllVdw0003Yfny5fjXf/1XrFu3Dp///OcRj8dx/vnnO+vktY7udZ45c2bOz2OxGKZOncp1zvCVr3wFPT09WLBgAaLRKEZHR3H11Vfj3HPPBQCusyGk1rWjowPz588fM4b62ZQpU0LNj0KGVJxly5Zhw4YNeOSRRyo9lXHHli1bcNlll+H+++9HfX19paczbkmlUjjqqKPwne98BwBwxBFHYMOGDbj55ptx/vnnV3h244df//rX+MUvfoHbb78dhxxyCJ566ilcfvnlmD17Ntd5AsOjpYBMnz4d0Wh0TFZHZ2cn2traKjSr2uWSSy7BPffcgwcffBBz5sxxvt/W1oahoSF0dXXl3N+9zm1tbZ6vg/oZSR8dbd++HUceeSRisRhisRhWr16N66+/HrFYDK2trVxnAWbNmoWDDz4453sHHXQQNm/eDCC7TsU+N9ra2rB9+/acn4+MjGDXrl1c5wxf/OIX8ZWvfAUf//jHceihh+K8887DFVdcgRUrVgDgOptCal1NfZZQyAQkHo9j0aJFWLVqlfO9VCqFVatWYfHixRWcWW1h2zYuueQS/Pa3v8UDDzwwJty4aNEi1NXV5azzpk2bsHnzZmedFy9ejGeeeSbnj+f+++9Hc3PzmE1lonLyySfjmWeewVNPPeX8O+qoo3Duuec6t7nO+hx//PFjyge88MIL2HvvvQEA8+fPR1tbW8469/T04NFHH81Z566uLqxfv965zwMPPIBUKoVjjjmmDM+i+tm9ezcikdxtKxqNIpVKAeA6m0JqXRcvXoyHH34Yw8PDzn3uv/9+HHjggaGPlQAw/ToMd9xxh51IJOzbbrvN3rhxo/2Zz3zGbmlpycnqIMX57Gc/ayeTSfuhhx6yt23b5vzbvXu3c5+LL77Ynjt3rv3AAw/Yjz/+uL148WJ78eLFzs9VWvD73/9++6mnnrLvvfdee8aMGUwLLoE7a8m2uc4SPPbYY3YsFrOvvvpq+8UXX7R/8Ytf2JMmTbL/53/+x7nPNddcY7e0tNi/+93v7L///e/2GWec4Zm+esQRR9iPPvqo/cgjj9j777//hE8LdnP++efbe+21l5N+/Zvf/MaePn26/aUvfcm5D9c5HL29vfaTTz5pP/nkkzYA+9prr7WffPJJ+/XXX7dtW2Zdu7q67NbWVvu8886zN2zYYN9xxx32pEmTmH5dKW644QZ77ty5djwet48++mh77dq1lZ5STQHA89+tt97q3GfPnj325z73OXvKlCn2pEmT7I985CP2tm3bcsZ57bXX7FNPPdVuaGiwp0+fbv/Lv/yLPTw8XOZnU1vkCxmuswx33323vXDhQjuRSNgLFiyw/+u//ivn56lUyv7a175mt7a22olEwj755JPtTZs25dxn586d9jnnnGM3Njbazc3N9oUXXmj39vaW82lUNT09PfZll11mz507166vr7f32Wcf+6tf/WpOOi/XORwPPvig52fy+eefb9u23Lo+/fTT9gknnGAnEgl7r732sq+55hrtuVu27SqJSAghhBBSQ9AjQwghhJCahUKGEEIIITULhQwhhBBCahYKGUIIIYTULBQyhBBCCKlZKGQIIYQQUrNQyBBCCCGkZqGQIYQQQkjNQiFDCBn3zJs3D9ddd12lp0EIMQCFDCFElAsuuABnnnkmAOA973kPLr/88rI99m233YaWlpYx31+3bh0+85nPlG0ehJDyEav0BAghpBRDQ0OIx+Ohf3/GjBmCsyGEVBOMyBBCjHDBBRdg9erV+OEPfwjLsmBZFl577TUAwIYNG3DqqaeisbERra2tOO+887Bjxw7nd9/znvfgkksuweWXX47p06fjlFNOAQBce+21OPTQQzF58mS0t7fjc5/7HPr6+gAADz30EC688EJ0d3c7j/eNb3wDwNijpc2bN+OMM85AY2Mjmpub8bGPfQydnZ3Oz7/xjW/gHe94B37+859j3rx5SCaT+PjHP47e3l6zi0YICQyFDCHECD/84Q+xePFifPrTn8a2bduwbds2tLe3o6urCyeddBKOOOIIPP7447j33nvR2dmJj33sYzm//9Of/hTxeBx//etfcfPNNwMAIpEIrr/+ejz77LP46U9/igceeABf+tKXAADHHXccrrvuOjQ3NzuP94UvfGHMvFKpFM444wzs2rULq1evxv33349XXnkFZ599ds79Xn75Zdx111245557cM8992D16tW45pprDK0WISQsPFoihBghmUwiHo9j0qRJaGtrc77/ox/9CEcccQS+853vON/7yU9+gvb2drzwwgs44IADAAD7778/vve97+WM6fbbzJs3D9/+9rdx8cUX48Ybb0Q8HkcymYRlWTmPl8+qVavwzDPP4NVXX0V7ezsA4Gc/+xkOOeQQrFu3Du985zsBpAXPbbfdhqamJgDAeeedh1WrVuHqq6/WWxhCiCiMyBBCysrTTz+NBx98EI2Njc6/BQsWAEhHQRSLFi0a87t//vOfcfLJJ2OvvfZCU1MTzjvvPOzcuRO7d+/2/fjPPfcc2tvbHREDAAcffDBaWlrw3HPPOd+bN2+eI2IAYNasWdi+fXug50oIMQ8jMoSQstLX14fTTz8d3/3ud8f8bNasWc7tyZMn5/zstddew4c+9CF89rOfxdVXX42pU6fikUcewUUXXYShoSFMmjRJdJ51dXU5X1uWhVQqJfoYhBB9KGQIIcaIx+MYHR3N+d6RRx6J//3f/8W8efMQi/n/CFq/fj1SqRT+4z/+A5FIOpj861//uuTj5XPQQQdhy5Yt2LJlixOV2bhxI7q6unDwwQf7ng8hpDrg0RIhxBjz5s3Do48+itdeew07duxAKpXCsmXLsGvXLpxzzjlYt24dXn75Zdx333248MILi4qQ/fbbD8PDw7jhhhvwyiuv4Oc//7ljAnY/Xl9fH1atWoUdO3Z4HjktWbIEhx56KM4991w88cQTeOyxx/DJT34S7373u3HUUUeJrwEhxCwUMoQQY3zhC19ANBrFwQcfjBkzZmDz5s2YPXs2/vrXv2J0dBTvf//7ceihh+Lyyy9HS0uLE2nx4vDDD8e1116L7373u1i4cCF+8YtfYMWKFTn3Oe6443DxxRfj7LPPxowZM8aYhYH0EdHvfvc7TJkyBSeeeCKWLFmCffbZB7/61a/Enz8hxDyWbdt2pSdBCCGEEBIGRmQIIYQQUrNQyBBCCCGkZqGQIYQQQkjNQiFDCCGEkJqFQoYQQgghNQuFDCGEEEJqFgoZQgghhNQsFDKEEEIIqVkoZAghhBBSs1DIEEIIIaRmoZAhhBBCSM3y/wMhN526JISHewAAAABJRU5ErkJggg==\n" }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from random import sample\n", "import numpy as np\n", "from datetime import datetime\n", "from matplotlib import pyplot as plt\n", "\n", "# digits from 1 to 9\n", "digits = np.arange(1,10)\n", "\n", "problem = np.array([[8, 0, 6, 2, 0, 9, 0, 1, 5],\n", " [9, 5, 0, 3, 0, 8, 7, 0, 0],\n", " [4, 0, 0, 1, 0, 0, 3, 0, 9],\n", " [7, 9, 3, 4, 8, 5, 0, 0, 0],\n", " [0, 0, 0, 7, 0, 0, 0, 0, 4],\n", " [0, 8, 4, 6, 0, 3, 9, 5, 7],\n", " [0, 0, 0, 0, 3, 4, 2, 0, 0],\n", " [3, 0, 9, 0, 0, 0, 1, 0, 8],\n", " [6, 0, 7, 0, 2, 0, 0, 0, 3]])\n", "\n", "# clues idx is a tuple that contains the coordinates of the clues.\n", "# It can be used for indexing non-zero values in the problem\n", "clues_idx = np.nonzero(problem)\n", "\n", "# Conversely, gaps_idx is a tuple that contains the coordinates of the zeros. \n", "# It is used for indexing the values we need to fill in.\n", "\n", "gaps_idx = np.nonzero(problem == 0)\n", "\n", "# We know that a valid solution is a permutation of the digits from 1 to 9 repeated 9 times. Let us find the digits that\n", "# are missing. digit_count counts, starting with zero the number of digits present in the problem:\n", "digit_count = np.bincount(problem.flatten())\n", "\n", "# the size of the problem (N):\n", "problem_size = digit_count[0]\n", "\n", "# HYPER-PARAMETERS\n", "# Hyper-parameter R, default: N-R = 2\n", "in_chromosome_size = problem_size -2 \n", "\n", "# Hyper-parameter 2, population size, default: 500 \n", "population_size = 500\n", "\n", "# Hyperparameter 3, number of iterations, default: 1000:\n", "num_iter = 1000\n", "\n", "# Hyperparameter 4, number of survivals in each generation: default 10\n", "num_survivals = 10\n", "# Hyperparameter 5, Number of iterations without improvement: default: 10\n", "reset_it = 10\n", "\n", "# The missing values are going to be 9 - the count of digits, the zeros can be ignored:\n", "missing_count = 9 - digit_count\n", "\n", "# OK, Let's start\n", "init_time = datetime.now()\n", "\n", "# Let's create a numpy array with the digits that we need to fill in: \n", "candidate_digits = np.array([], dtype='int32')\n", "\n", "\n", "for digit in digits:\n", " candidate_digits = np.append(candidate_digits, np.repeat(digit, missing_count[digit]))\n", "\n", "\n", "def is_permutation(elements):\n", " # returns 0 if row is a permutation of digits from 1 to 9\n", " return 9 - len(np.unique(elements))\n", "\n", "def fitness(solution):\n", " res = 0\n", " # check that rows are consistent\n", " for i in range(9):\n", " res += is_permutation(solution[i])\n", " \n", " # check that columns are consistent\n", " for j in range(9):\n", " res += is_permutation(solution[:,j])\n", " \n", " # check that blocks are consistent\n", " for k in range(9): # 0, 1, 2, 3, 4, 5, 6, 7, 8\n", " row_index = 3*(k//3) # 3 * (0, 0, 0, 1, 1, 1, 2, 2, 2)\n", " col_index = 3*(k%3) # 3 * (0, 1, 2, 0, 1, 2, 0, 1, 2) \n", " res += is_permutation(solution[row_index:row_index + 3, col_index:col_index+3])\n", "\n", " # check consistency with problem definition\n", " # indices of clues\n", " res += sum(abs(problem[clues_idx]-solution[clues_idx]))\n", "\n", " # check if solution is complete\n", " res += np.sum(solution == 0)\n", " return res\n", "\n", "\n", "\n", "# our genome consists of shuffling the candidate digits and placing the digits in the \n", "# gaps\n", " \n", "genome = np.zeros((population_size, 9, 9))\n", " \n", "for k in range(population_size):\n", " # shuffle the candidates\n", " np.random.shuffle(candidate_digits)\n", " \n", " #init candidate as problem\n", " genome[k, :, :] = np.copy(problem)\n", " #fill in sudoku, by placing the digits where the problem is zero\n", " np.place(genome[k, :, :], genome[k, :, :] == 0, candidate_digits)\n", "\n", "# The simplest genome generation strategy is however to just fill the zeros with digits\n", "# np.place(genome, genome==0, [1, 2, 3, 4, 5, 6, 7, 8, 9])\n", "\n", "it = 0\n", "iteration_error = np.zeros(num_iter)\n", "while it < num_iter:\n", " # reset the fitness function\n", " fitness_array = np.zeros(population_size)\n", " \n", " for k in range(population_size): \n", " # calculate fitness function of candidate k\n", " fitness_array[k] = fitness(genome[k,:,:])\n", "\n", " \n", " # Find the fittest!\n", " fitness_array_sorted_idx = np.argsort(fitness_array)\n", " fittest = fitness_array_sorted_idx[0:num_survivals]\n", "\n", " iteration_error[it] = fitness_array[fittest[0]]\n", " reset = (it >= reset_it) and (sum(abs(iteration_error[it-reset_it:it] - iteration_error[it])) == 0)\n", " if reset:\n", " \n", " digit_count = np.bincount(problem.flatten())\n", "\n", " # The missing values are going to be 9 - the count of digits, the zeros can be ignored:\n", " missing_count = 9 - digit_count\n", "\n", " # Let's create a numpy array with the digits that we need to fill in: \n", " candidate_digits = np.array([], dtype='int32')\n", "\n", "\n", " for digit in digits:\n", " candidate_digits = np.append(candidate_digits, np.repeat(digit, missing_count[digit]))\n", "\n", " genome = np.zeros((population_size, 9, 9))\n", " \n", " for k in range(population_size):\n", " # shuffle the candidates\n", " np.random.shuffle(candidate_digits)\n", " \n", " #init candidate as problem\n", " genome[k, :, :] = np.copy(problem)\n", " #fill in sudoku, by placing the digits where the problem is zero\n", " np.place(genome[k, :, :], genome[k, :, :] == 0, candidate_digits)\n", " \n", " continue \n", " \n", " sol = genome[fittest[0],:,:]\n", " # print('Iteration: ' + str(it))\n", " # print(iteration_error[it])\n", " # print(sol) # We might have found already a solution\n", " \n", " if fitness_array[fittest[0]] == 0:\n", " break\n", " else:\n", " # Let us create the next generation\n", " # take ten survivals\n", " mutations = np.zeros((population_size,9,9))\n", " # randomly combine rows of the best solutions\n", " for k in range(population_size):\n", " # Init mutation_k as problem\n", " mutation_k = np.copy(problem)\n", " \n", " \n", " # we select the parent randomly from the survivals\n", " np.random.shuffle(fittest)\n", " parent_a = genome[fittest[0],:,:]\n", " \n", " \n", " # we first select some values to fill in randomly\n", " pos_to_fill_in_a = np.random.choice(np.arange(problem_size), 95*problem_size//100, replace=False)\n", " \n", " mutation_idx_a = (gaps_idx[0][pos_to_fill_in_a], gaps_idx[1][pos_to_fill_in_a])\n", " \n", " # we fill in the values selecting them from the parent\n", " mutation_k[mutation_idx_a] = parent_a[mutation_idx_a]\n", " \n", " # Now we fill in the rest of the values randomly\n", " digit_count = np.bincount(mutation_k.flatten())\n", " \n", " missing_count = 9 - digit_count\n", " candidate_digits = np.array([], dtype='int32')\n", " for digit in digits:\n", " candidate_digits = np.append(candidate_digits, np.repeat(digit, missing_count[digit]))\n", " \n", " np.random.shuffle(candidate_digits)\n", " np.place(mutation_k, mutation_k == 0, candidate_digits)\n", " \n", " \n", " mutations[k,:,:] = np.copy(mutation_k)\n", " \n", " # copy mutation to genome\n", " genome = np.copy(mutations)\n", " \n", " # We increase the number of iterations\n", " it+=1\n", "\n", "end_time = datetime.now()\n", "duration = end_time - init_time\n", "print(\"all righty, i finished the Sudoku in {0} seconds and {1} iterations: \".format(duration.total_seconds(), it))\n", "print(\"Best solution is:\")\n", "print(sol)\n", "plt.plot(iteration_error)\n", "plt.xlabel('Iteration')\n", "plt.ylabel('Error')\n" ], "metadata": { "collapsed": false } }, { "cell_type": "markdown", "source": [ "### Questions\n", "1. Run the algorithm above and write down the number of iterations and the execution time. Did the algorithm find an \n", "optimal solution? You can try again if you think the algorithm did not find an optimal solution. Do you think the algorithm is better than a human? (spoiler alert: the algorithm is not very good and will probably need several attempts to find a solution)\n", "\n", "2. Reason with an AI assistant about the algorithm, and ask for an explanation of the code in the cell above in simple terms.\n", "\n", "\n", "3. As described in the explanation of this approach, the algorithm may converge to a *local minimum*, a solution with a low number of errors, but that\n", "cannot be fixed with a permutation of digits. If the algorithm detects that there is no improvement, it will reset the \n", "entire population and start again (and we will see a drastic increase in the error). Looking at the graph that shows the error against the iterations, do you think the algorithm reset the entire population at any time? How many times do you think the reset function was executed?\n", "\n", "4. This is a naive approach because to generate the solution, Ask an AI assistant what is the search space of the problem, and how many possible solutions there are using this naive approach. Now, look for the assessment of the search space of the problem in the section above and use this prompt template to ask the AI assistant again:\n", "> I found the following information about the search space of the problem: [Look for the assessment of the complexity of the problem in the section above and paste it here]. Can you tell explain it to me in simple terms?\n", "\n", "\n", "5. The search space is just vast. As an AI assistant answer how big is it using this prompt:\n", "\n", "> How extraordinarily large is the number of possible combinations obtained? Can you provide me some illustrative examples? Be imaginative!" ], "metadata": { "collapsed": false } }, { "cell_type": "markdown", "source": [ "## Approach 2: Columns approach\n", "Approach 1 is naive in the sense that it does not require an in-depth knowledge of Sudoku to program the algorithm, but \n", "obviously, if we have some knowledge of the problem at hand, we can deliver more efficient solutions, but they might come\n", "at the expense of complexity, and therefore costs, development costs and/or computational costs. \n", "\n", "Let us again look at the solution of the problem above:\n", "

\"Sudoku-by-L2G-20050714.svg\"
Tim Stellmach - public domain, wikipedia

\n", "\n", "We know that each column is a permutation of the digits in [1-9], so, what if instead of assigning to every unknown cell \n", "an index, we use two indices, one for the columns, and another one for the rows. for instance, now our solution will be\n", "\n", "- Column 1: $[s_{31}, s_{71}, s_{71}, s_{71}] = [1, 9, 2, 3]$\n", "- Column 2: $[s_{22}, s_{42}, s_{52}, s_{62}, s_{82}, s_{92}] = [7, 5, 2, 1, 8, 4]$\n", "- Column 3: $[s_{13}, s_{23}, s_{43}, s_{53}, s_{63}, s_{73}, s_{83}, s_{93}] = [4, 2, 9, 6, 3, 1, 7, 5]$\n", "- Column 4: $[s_{14}, s_{34}, s_{44}, s_{64}, s_{74}, s_{94}] = [6, 3, 7, 9, 5, 2]$\n", "- Column 5: $[s_{35}, s_{55}, s_{75}] = [4, 5, 3]$\n", "- Column 6: $[s_{16}, s_{36}, s_{46}, s_{56}, s_{96}] = [8, 2, 1, 4, 7, 6]$\n", "- Column 7: $[s_{17}, s_{27}, s_{37}, s_{47}, s_{57}, s_{67}, s_{87}, s_{97}] = [9, 3, 5, 4, 7, 8, 6, 1]$\n", "- Column 8: $[s_{18}, s_{28}, s_{48}, s_{58}, s_{68}, s_{88}] = [1, 4, 2, 9, 5, 3]$\n", "- Column 9: $[s_{19}, s_{29}, s_{39}, s_{79}] = [2, 8, 7, 4]$\n", "\n", "\n", "Again, even if at the beginning of the problem we do not know the exact value that we need to assign to each cell, \n", "it is very easy to know which values are going to be missing in each column, and we know that in the solution, the values \n", "in each column is going to be a permutation of the missing values. So, now, our problem consists of finding 9 \n", "permutations of different sizes! what is now the number of potential solutions, the search space? well, it depends on \n", "the problem, but in this specific case, we need to multiply the number of possible combinations in each row, therefore \n", "the number of candidate solution in this case is:\n", "\n", "$$N_1!*N_2!*N_3!*N_4!*N_5!*N_6!*N_7!*N_8!*N_9! = 4!*6!*8!*6!*3!*6!*8!*3!*4! = 12582400952578867200000$$\n", "\n", "Compared to alternative 1:\n", "\n", "$$\\frac{51!}{6!·7!·6!·8!·5!·4!·6!·4!·5!}=2465536997482928914408092530982635167547392$$\n", "\n", "The search space is now tiny!\n", "\n", "### Initialisation\n", "Again, the first step is to generate an initial **genome** (all genes of a set of possible solutions). A gene is going to \n", "represent the value of a digit in a position of the Sudoku, and all the genes or chromosome of a solution, all the values\n", "of all digits missing in the problem. \n", "Basically, to generate the genome of the first population, we can generate just as many permutations of the\n", "values missing in each column as the size of the initial population. Let us note as $c_j \\quad j \\in [1-9]$ the set of \n", "missing values in column $j$. Basically, we need to obtain $P$ permutations of every $c_j$. \n", "We can use the same function $\\tau(c_j)$ to re-arranges the items of an array $c$ and returns a random permutation out \n", "of the $N_j!$ possible permutations. so, our initial genome $G_0$ is going to be P different sets of permutations of the 9 columns: \n", "\n", "$G_0 = [g_{01}, g_{02}, ...g_{0P}]$\n", "\n", "$g_{0k} = [\\tau(c_j) \\quad \\forall k \\in [1, P] \\forall j \\in [1-9]$\n", "\n", "Again, the numpy function [shuffle](https://numpy.org/doc/stable/reference/random/generated/numpy.random.shuffle.html) provides such a re-arrangement.\n", "\n", "\n", "### Fitness function\n", "We can use the same fitness function as in the previous approach.\n", "\n", "### Selection function\n", "We can apply the same selection function as in the previous approach.\n", "\n", "### Crossover and mutation\n", "Now, let us take a different approach for the cross-over, what we are going to do is to take a number of columns from the \n", "parent, and copy them, and then create a mutation by shuffling some values of the remaining columns.\n", "\n", "Let us note as $R_c$ the number of columns that are passed to the children without mutations. Again, this is a combination\n", "of the 9 columns, and the number of possible combinations is: \n", "\n", "$C^9_{R_c} = \\frac{9!}{R_c!(9-R_c)!}$\n", "\n", "For instance, if we set this parameter to 8, there are 9 possible combinations. \n", "\n", "Now, we are going to mutate the remaining columns. Let us refer to column j to one of the columns that will mutate. \n", "In this case, Let us note as $N_j$ the unknown digits in column j, $R_j$ the number of digits (or genes) of the \n", "parent that we copy to column j, and $N_j-R_j$ the number of genes that mutate in that column. There are:\n", "\n", "$C^{N_j}_{R_j} = \\frac{N_j!}{R_j!(N_j-R_j)!}$\n", "\n", "Possible combinations of genes and $(N_j-R_j)!$ permutations of the genes that mutate. So, again, there are:\n", "\n", "$C^{N_j}_{R_j}*(N_j-R_j)! = \\frac{N_j!}{R_j!}$\n", "\n", "Again, this is a combination, but note that, now, the index of the column j is random (we did a random selection of \n", "columns), so the maximum number of digits missing are found in columns 3 and 7 that are both missing 8 numbers. \n", "So, for instance, if we set $R_c$ to 8, so that we copy 8 columns from the parent, there will be 9 combinations of columns \n", "to pass as-is to the next generation.\n", "Now, say we fix $(N_j - R_j) to 2, so that we shuffle at most 2 values. We will have, at most: \n", "\n", "$9*\\frac{8!}{6!} = 9*8*7 = 504$\n", "\n", "Possible ways to mutate a parent if the algorithm selects to mutate column 3 or column 7. And if we select 10 survivals, \n", "we may get an estimation of the total number of offspring as 5040. \n", "\n", "There are two things that we need to observe here. First is that the number of combinations is significantly smaller, \n", "just as the search space, so we can deal with smaller populations in every generation, which will make each iteration \n", "faster, or take another strategies, like increasing the number of survivals in each generation, or the number of\n", " columns that we shuffle, to explore the search space faster. \n", "\n", "The other important thing is that there is uncertainty in the total number of possible offspring, because not\n", "all the columns are missing the same number of values and, since the parameters of the algorithm are fixed, the algorithm\n", "is not going to be as stable as in the first approach.\n", "\n", "### Termination\n", "We will terminate using the same approach as before.\n", "\n", "\n", "### Implementation\n", "Ok, the following Python script implements this approach. To try it, you just need to provide the values of your Sudoku \n", "as a Python Array where the digits in [1-9] define the clues or filled digits in your Sudoku, and the 0s represent the \n", "gaps.\n", "\n", "#### Hyper-parameters\n", "The parameters that control the behaviour of the algorithm, or hyperparameters:\n", "- Number of columns that are passed to the next generation ($R_c$). Default: 8\n", "- Number of genes that are passed to children in each generation (R). Default: 2 \n", "- Population size, the population size of each generation (P), default: 50\n", "- Number of iterations, default: 1000:\n", "- Number of survivals in each generation, default 10\n", "- Number of iterations without improvement, default 100\n", " \n" ], "metadata": { "collapsed": false } }, { "cell_type": "code", "execution_count": 4, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "all righty, i finished the Sudoku in 7.524293 seconds and 447 iterations: \n", "Best solution is:\n", "[[8. 3. 6. 2. 7. 9. 4. 1. 5.]\n", " [9. 5. 1. 3. 4. 8. 7. 6. 2.]\n", " [4. 7. 2. 1. 5. 6. 3. 8. 9.]\n", " [7. 9. 3. 4. 8. 5. 6. 2. 1.]\n", " [1. 6. 5. 7. 9. 2. 8. 3. 4.]\n", " [2. 8. 4. 6. 1. 3. 9. 5. 7.]\n", " [5. 1. 8. 9. 3. 4. 2. 7. 6.]\n", " [3. 2. 9. 5. 6. 7. 1. 4. 8.]\n", " [6. 4. 7. 8. 2. 1. 5. 9. 3.]]\n" ] }, { "data": { "text/plain": "[]" }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" }, { "data": { "text/plain": "
", "image/png": "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\n" }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from random import sample\n", "import numpy as np\n", "from matplotlib import pyplot as plt\n", "from datetime import datetime\n", "\n", "# digits from 1 to 9\n", "digits = np.arange(1,10)\n", "\n", "problem = np.array([[8, 0, 6, 2, 0, 9, 0, 1, 5],\n", " [9, 5, 0, 3, 0, 8, 7, 0, 0],\n", " [4, 0, 0, 1, 0, 0, 3, 0, 9],\n", " [7, 9, 3, 4, 8, 5, 0, 0, 0],\n", " [0, 0, 0, 7, 0, 0, 0, 0, 4],\n", " [0, 8, 4, 6, 0, 3, 9, 5, 7],\n", " [0, 0, 0, 0, 3, 4, 2, 0, 0],\n", " [3, 0, 9, 0, 0, 0, 1, 0, 8],\n", " [6, 0, 7, 0, 2, 0, 0, 0, 3]])\n", "\n", "# clues idx is a tuple that contains the coordinates of the clues.\n", "# It can be used for indexing non-zero values in the problem\n", "clues_idx = np.nonzero(problem)\n", "\n", "# Conversely, gaps_idx is a tuple that contains the coordinates of the zeros. \n", "# It is used for indexing the values we need to fill in.\n", "\n", "gaps_idx = np.nonzero(problem == 0)\n", "\n", "# We know that a valid solution is a collection of permutation of the digits from 1 to 9 repeated 9 times. Let us find the digits that\n", "# are missing. digit_count counts, starting with zero the number of digits present in the problem:\n", "digit_count = np.bincount(problem.flatten())\n", "\n", "# the number of gaps:\n", "problem_size = digit_count[0]\n", "\n", "# Hyper-parameters\n", "\n", "# Population size\n", "population_size = 50\n", "\n", "# columns (chromosomes) to pass to next generation (R_c)\n", "keep_cols = 8\n", "\n", "# maximum number of values to shuffle (N-R)\n", "cells_to_shuffle = 2\n", "\n", "# Number of iterations\n", "num_iter = 1000\n", "\n", "# number of survivals\n", "num_survivals = 10\n", "\n", "# maximum number of iterations without improvement\n", "reset_it = 100\n", "\n", "# The missing values are going to be 9 - the count of digits, the zeros can be ignored:\n", "missing_count = 9 - digit_count\n", "\n", "def get_missing_per_column(column):\n", " column_count = np.bincount(column)\n", " column_count_padded = np.zeros(10)\n", " column_count_padded[0:len(column_count)] = column_count\n", " return digits[column_count_padded[1:]==0] \n", "\n", "\n", "def get_missing(prob):\n", " m_per_column = np.zeros((9,9), dtype='int32')\n", " for j in range(9):\n", " missing_values = get_missing_per_column(prob[:,j]) \n", " m_per_column[0:len(missing_values), j] = missing_values\n", " return m_per_column\n", "\n", "\n", "def is_permutation(elements):\n", " # returns 0 if row is a permutation of digits from 1 to 9\n", " return 9 - len(np.unique(elements))\n", "\n", "def fitness(solution):\n", " res = 0\n", " # check that rows are consistent\n", " for i in range(9):\n", " res += is_permutation(solution[i])\n", " \n", " # check that columns are consistent\n", " for j in range(9):\n", " res += is_permutation(solution[:,j])\n", " \n", " # check that blocks are consistent\n", " for k in range(9): # 0, 1, 2, 3, 4, 5, 6, 7, 8\n", " row_index = 3*(k//3) # 3 * (0, 0, 0, 1, 1, 1, 2, 2, 2)\n", " col_index = 3*(k%3) # 3 * (0, 1, 2, 0, 1, 2, 0, 1, 2) \n", " res += is_permutation(solution[row_index:row_index + 3, col_index:col_index+3])\n", "\n", " # check consistency with problem definition\n", " # indices of clues\n", " res += sum(abs(problem[clues_idx]-solution[clues_idx]))\n", "\n", " # check if solution is complete\n", " res += np.sum(solution == 0)\n", " return res\n", "\n", "\n", "init_time = datetime.now()\n", "\n", "# Now our genome consists of shuffling the candidate digits of every row and placing the digits in the \n", "# gaps\n", " \n", "genome = np.zeros((population_size, 9, 9))\n", "\n", "# Initial missing values in problem\n", "missing_per_column = get_missing(problem) \n", "\n", "\n", "for k in range(population_size):\n", " \n", " #init candidate as problem\n", " genome[k, :, :] = np.copy(problem)\n", " \n", " #fill in sudoku, by placing the digits where the problem is zero\n", " for j in range(9):\n", " candidate_digits_j = missing_per_column[missing_per_column[:, j]>0,j]\n", " np.random.shuffle(candidate_digits_j) \n", " np.place(genome[k, :, j], genome[k, :, j] == 0, candidate_digits_j)\n", "\n", "# The simplest genome generation strategy is however to just fill the zeros with digits\n", "# np.place(genome, genome==0, [1, 2, 3, 4, 5, 6, 7, 8, 9])\n", "\n", "it = 0\n", "iteration_error = np.zeros(num_iter)\n", "while it < num_iter:\n", " # reset the fitness function\n", " fitness_array = np.zeros(population_size)\n", " \n", " for k in range(population_size): \n", " # calculate fitness function of candidate k\n", " fitness_array[k] = fitness(genome[k,:,:])\n", "\n", " \n", " # Find the fittest!\n", " fitness_array_sorted_idx = np.argsort(fitness_array)\n", " fittest = fitness_array_sorted_idx[0:num_survivals]\n", "\n", " iteration_error[it] = fitness_array[fittest[0]]\n", " reset = (it >= reset_it) and (sum(abs(iteration_error[it-reset_it:it] - iteration_error[it])) == 0)\n", " if reset:\n", " genome = np.zeros((population_size, 9, 9))\n", " \n", " for k in range(population_size):\n", " # init candidate as problem\n", " genome[k, :, :] = np.copy(problem)\n", " \n", " # fill in sudoku, by placing the digits where the problem is zero\n", " for j in range(9):\n", " candidate_digits_j = missing_per_column[missing_per_column[:, j]>0,j]\n", " np.random.shuffle(candidate_digits_j) \n", " np.place(genome[k, :, j], genome[k, :, j] == 0, candidate_digits_j)\n", "\n", " continue\n", " \n", " sol = genome[fittest[0],:,:]\n", " \n", "\n", " # print(sol)\n", " # We might have found already a solution\n", " if iteration_error[it] == 0:\n", " break\n", " else:\n", " # Let us create the next generation\n", " # take ten survivals\n", " mutations = np.zeros((population_size,9,9))\n", " \n", " # randomly combine rows of the best solutions\n", " for k in range(population_size):\n", " # Init mutation_k as problem\n", " mutation_k = np.copy(problem)\n", " \n", " \n", " # we select the parent randomly from the survivals\n", " np.random.shuffle(fittest)\n", " parent_a = genome[fittest[0],:,:]\n", " \n", " \n", " # we first select columns to fill in randomly\n", " columns_to_fill_in_a = np.random.choice(np.arange(9), keep_cols, replace=False)\n", " \n", " \n", " # we fill all the values selecting them from the parent\n", " mutation_k = parent_a\n", " \n", " \n", " \n", " # Now we create permutations of the columns that we want to mutate\n", " missing_column_k = np.setdiff1d(np.arange(9), columns_to_fill_in_a)\n", " for j in missing_column_k:\n", " # values missing in the original problem\n", " candidate_digits_j = missing_per_column[missing_per_column[:, j]>0,j]\n", " #if we are missing 0 or 1 value in a column, we will also copy it\n", " if len(candidate_digits_j >= 2):\n", " # reorder the candidate digits\n", " np.random.shuffle(candidate_digits_j)\n", " # pick at most cells_to_shuffle digits\n", " digits_to_remove = candidate_digits_j[0:min(cells_to_shuffle, len(candidate_digits_j))]\n", " # set them to 0\n", " np.place(mutation_k[:,j], np.isin(mutation_k[:,j], digits_to_remove), 0)\n", " \n", " # shuffle the digits\n", " np.random.shuffle(digits_to_remove)\n", " \n", " # set the values again\n", " np.place(mutation_k[:, j], mutation_k[:, j] == 0, digits_to_remove) \n", " \n", " \n", " mutations[k,:,:] = np.copy(mutation_k)\n", " \n", " # copy mutation to genome\n", " genome = np.copy(mutations)\n", " \n", " # We increase the number of iterations\n", " it+=1\n", "\n", "end_time = datetime.now()\n", "duration = end_time - init_time\n", "print(\"all righty, i finished the Sudoku in {0} seconds and {1} iterations: \".format(duration.total_seconds(), it))\n", "print(\"Best solution is:\")\n", "print(sol)\n", "plt.plot(iteration_error)" ], "metadata": { "collapsed": false } }, { "cell_type": "markdown", "source": [ "### Analysis Questions\n", "1. Run the algorithm above and write down the number of iterations and the execution time. Did the algorithm find an \n", "optimal solution? Do you think this approach is faster?\n", "\n", "2. Ask an AI assistant to explain this algorithm to you in simple terms, and ask also if this algorithm is more efficient, and ask for simple explanations of why.\n", "\n", "\n", "3. Look for the description of the size of the search space in the description above and ask again an AI assistant to provide some illustrative examples of how big this new search space is.\n", "\n", "\n", "4. Ask an AI assistant again to describe what hyperparameters are and what are the hyperparameters of this algorithm. Ask if it can suggest a better set of hyperparameters to solve the problem faster. Try the suggested hyperparameters and compare the results. This process is called **hyperparameter tuning,** and it is a very important part of AI. Was the AI assistant able to suggest a better set of hyperparameters?\n", "\n", "5. This strategy exploits the fact that columns are permutations of digits. What other strategies can you think of to\n", "solve the problem faster? How would you improve the algorithm? (Feel free to reason with your AI assistant about better ways to solve this problem)\n", "\n", "\n" ], "metadata": { "collapsed": false } } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "pycharm": { "stem_cell": { "cell_type": "raw", "source": [], "metadata": { "collapsed": false } } } }, "nbformat": 4, "nbformat_minor": 1 }